IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3/Vk/VkMsgClient.z/VkMsgClient

Text File | 2002-10-03 | 23.7 KB | 595 lines

VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))                                                VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))



NNNNAAAAMMMMEEEE
     VkMsgClient - ViewKit application interface to the ViewKit Message
     Facility

HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
     #include <Vk/VkMsgClient.h>

PPPPUUUUBBBBLLLLIIIICCCC PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL SSSSUUUUMMMMMMMMAAAARRRRYYYY
   CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr////DDDDeeeessssttttrrrruuuuccccttttoooorrrr
          VkMsgClient(VkMsgFacilityCallback callback,
                      void *client_data);

          void ~VkMsgClient(void);


   MMMMeeeessssssssaaaaggggeeee PPPPaaaatttttttteeeerrrrnnnnssss
           void registerPattern(char* op,
                      VkMsgCategory category = VK_MSG_OBSERVE);

           void updatePatterns(void);

           VkMsgStatus registerPattern(VkMsgPattern pat);

           VkMsgStatus unregisterPattern(VkMsgPattern pat);

           VkMsgStatus destroyPattern(VkMsgPattern pat);


   MMMMeeeessssssssaaaaggggeeee AAAAccccttttiiiioooonnnnssss
           VkMsgPattern addAction(char* op, VkMsgClientAction proc,
                                  void *client_data,
                                  VkMsgActionType type,
                                  Boolean deleteMessage = True);

           VkMsgPattern createAction(char* op, VkMsgClientAction proc,
                                    void *client_data,
                                    VkMsgActionType type,
                                    Boolean deleteMessage = True);

           void removeAction(VkMsgPattern pat);

           Boolean findAction(char* name, VkMsgClientAction* proc,
                              void **client_data,
                              Boolean *deleteMessage);


   MMMMeeeessssssssaaaaggggeeee TTTTrrrraaaannnnssssllllaaaattttiiiioooonnnnssss
           void addTranslation(char* name,
                               VkMsgClientAction proc,
                               void *client_data,
                               Boolean deleteMessage = True);




                                                                        PPPPaaaaggggeeee 1111






VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))                                                VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))



           void removeTranslation(char* name);


   SSSSeeeennnnddddiiiinnnngggg NNNNoooottttiiiicccceeeessss
           void sendNotice(char* op, int argc, VkMsgArg* argv);

           void sendNotice(char* op);

           void sendStringNotice(char* op ...);

           void sendIntNotice(char* op ...);

           void sendFileNotice(char* op, char* file,
                               int argc, VkMsgArg* argv);

           void sendFileNotice(char* op, char* file);

           void sendStringFileNotice(char* op, char* file ...);

           void sendIntFileNotice(char* op, char* file ...);


   SSSSeeeennnnddddiiiinnnngggg RRRReeeeqqqquuuueeeessssttttssss
           VkMsgMessage sendRequest(char* op, int argc,
                                    VkMsgArg* argv);

           VkMsgMessage sendRequest(char* op);

           VkMsgMessage sendSyncRequest(char* op, int argc,
                                        VkMsgArg* argv,
                                int timeout = DEFAULT_SYNC_TIMEOUT);

           VkMsgMessage sendSyncRequest(char* op,
                                 int timeout = DEFAULT_SYNC_TIMEOUT);

           VkMsgMessage sendFileRequest(char* op, char* file,
                                         int argc, VkMsgArg* argv);

           VkMsgMessage sendFileRequest(char* op, char* file);

           VkMsgMessage sendSyncFileRequest(char* op, char* file,
                                           int argv, VkMsgArg* argv,
                                 int timeout = DEFAULT_SYNC_TIMEOUT);

           VkMsgMessage sendSyncFileRequest(char* op, char* file,
                                 int timeout = DEFAULT_SYNC_TIMEOUT);


   CCCCoooommmmppppoooossssiiiinnnngggg MMMMeeeessssssssaaaaggggeeee AAAArrrrgggguuuummmmeeeennnnttttssss
           void composeBegin(void);

           void composeAdd(VkMsgArg* arg);



                                                                        PPPPaaaaggggeeee 2222






VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))                                                VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))



           void composeAdd(char* val, VkMsgMode mode = VK_MSG_IN);

           void composeAdd(int ival, VkMsgMode mode = VK_MSG_IN);

           void composeAdd(unsigned char* bval, int len,
                           VkMsgMode mode = VK_MSG_IN);

           VkMsgArg* composeList(void);

           int composeNum(void);




CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     VkMsgClient is the normal way application code interacts with the message
     facility.  There are methods for sending and receiving messages,
     installing message actions, and registering interest in message patterns.

FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS
   VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt(((())))
           VkMsgClient(VkMsgFacilityCallback callback,
                      void *client_data);

           void ~VkMsgClient(void);


          The callback is called whenever messages are received for this
          client.

          However, usually messages are handled through message-specific
          callbacks (actions).  See the _a_d_d_A_c_t_i_o_n() method.

   rrrreeeeggggiiiisssstttteeeerrrrPPPPaaaatttttttteeeerrrrnnnn(((())))
           void registerPattern(char* op,
                         VkMsgCategory category = VK_MSG_OBSERVE);


          Express interest in messages whose operator string match the first
          argument.  The second argument should be _V_K__M_S_G__O_B_S_E_R_V_E or
          _V_K__M_S_G__H_A_N_D_L_E to deal with notices or requests, respectively.

          However, usually messages are handled through message-specific
          callbacks (actions).  See the _a_d_d_A_c_t_i_o_n() method, which
          automatically creates and register patterns.

   uuuuppppddddaaaatttteeeePPPPaaaatttttttteeeerrrrnnnnssss(((())))
           void updatePatterns(void);







                                                                        PPPPaaaaggggeeee 3333






VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))                                                VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))



          Call updatePatterns when you want to add new message patterns after
          connecting to the ToolTalk service.  To be safe, call this method
          after you are done using the _a_d_d_A_c_t_i_o_n() and _r_e_g_i_s_t_e_r_P_a_t_t_e_r_n()
          methods.

   aaaaddddddddAAAAccccttttiiiioooonnnn(((())))
           VkMsgPattern addAction(char* op,
                                  VkMsgClientAction proc,
                                  void *client_data,
                                  VkMsgActionType type,
                                  Boolean deleteMessage = True);


          Add a message-specific callback.  The first argument is the message
          operator string.  The second and third arguments are the callback
          and callback data to call.  The fourth argument is the type of
          action, _V_K__M_S_G__A_C_T_I_O_N__O_B_S_E_R_V_E (notices), _V_K__M_S_G__A_C_T_I_O_N__H_A_N_D_L_E
          (requests), _V_K__M_S_G__A_C_T_I_O_N__H_A_N_D_L_E__S_P_E_C_I_F_I_C (requests matching the
          exact pattern), _V_K__M_S_G__A_C_T_I_O_N__R_E_P_L_Y (replies to requests),
          _V_K__M_S_G__A_C_T_I_O_N__F_A_I_L (failed requests), _V_K__M_S_G__A_C_T_I_O_N__S_T_A_R_T (autostart
          of handlers to service requests).  The last argument specifies
          deletion of the message after the callback returns.

          Be sure to add your message actions before entering any Xt event
          loop.  Otherwise, messages may be received before the action is
          registered, and they will not be processed as expected.  The Xt
          event loop is entered when you call _V_k_A_p_p::_r_u_n(), or when you post a
          ViewKit dialog and a short, secondary event loop is entered.

   ccccrrrreeeeaaaatttteeeeAAAAccccttttiiiioooonnnn(((())))
           VkMsgPattern createAction(char* op,
                                     VkMsgClientAction proc,
                                     void *client_data,
                                     VkMsgActionType type,
                                     Boolean deleteMessage = True);


          Creates a message action, but doesn't register it yet.  You can then
          use ToolTalk routines like _V_k_M_s_g_P_a_t_t_e_r_n_A_r_g() to add argument types
          and values to the pattern before registering it with the
          _r_e_g_i_s_t_e_r_P_a_t_t_e_r_n() method.  Use the _r_e_g_i_s_t_e_r_P_a_t_t_e_r_n() method to
          register your pattern.

   rrrreeeemmmmoooovvvveeeeAAAAccccttttiiiioooonnnn(((())))
           void removeAction(VkMsgPattern pat);


          Removes an action.  The pattern is automatically unregistered.

   aaaaddddddddTTTTrrrraaaannnnssssllllaaaattttiiiioooonnnn(((())))





                                                                        PPPPaaaaggggeeee 4444






VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))                                                VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))



           void addTranslation(char* name,
                               VkMsgClientAction proc,
                               void *client_data,
                               Boolean deleteMessage = True);


          When using resource-specified patterns (vkmsgTranslations), adds a
          callback for the named translation.  Similar to the _a_d_d_A_c_t_i_o_n()
          method.

   rrrreeeemmmmoooovvvveeeeTTTTrrrraaaannnnssssllllaaaattttiiiioooonnnn(((())))
           void removeTranslation(char* name);


          Removes a translation.

   ffffiiiinnnnddddAAAAccccttttiiiioooonnnn(((())))
           Boolean findAction(char* name,
                              VkMsgClientAction* proc,
                              void **client_data,
                              Boolean *deleteMessage);


          Looks for a named action in this client for the operator string.
          Returns the callback, callback-data, and whether to delete the
          message after the callback returns.

   sssseeeennnnddddNNNNoooottttiiiicccceeee(((())))
           void sendNotice(char* op, int argc, VkMsgArg* argv);


          Send a notice.  The first argument is the operator string, the
          second argument is the number of message arguments, and the third
          argument is the array of message arguments.  Message arguments come
          in three types, _V_K__M_S_G__I_N_T__M_S_G__A_R_G__T_Y_P_E, _V_K__M_S_G__S_T_R_I_N_G__M_S_G__A_R_G__T_Y_P_E,
          and _V_K__M_S_G__B_S_T_R_I_N_G__M_S_G__A_R_G__T_Y_P_E.  Message arguments come in three
          modes, _V_K__M_S_G__I_N, _V_K__M_S_G__O_U_T, and _V_K__M_S_G__I_N_O_U_T.


           void sendNotice(char* op);


          Send a notice.  The first argument is the operator string, and the
          composed message arguments list is used (see the composeBegin and
          composeAdd methods).

   sssseeeennnnddddSSSSttttrrrriiiinnnnggggNNNNoooottttiiiicccceeee(((())))
           void sendStringNotice(char* op ...);







                                                                        PPPPaaaaggggeeee 5555






VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))                                                VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))



          Send a notice with only string arguments.  The first argument is the
          operator string.  The remaining arguments are a NULL-terminated list
          of string arguments for the message.

   sssseeeennnnddddIIIInnnnttttNNNNoooottttiiiicccceeee(((())))
           void sendIntNotice(char* op ...);


          Send a notice with only integer arguments.  The first argument is
          the operator string.  The remaining arguments are a NULL-terminated
          list of integer arguments for the message.  Note that you cannot
          send any zero arguments, since NULL terminates the list.

   sssseeeennnnddddFFFFiiiilllleeeeNNNNoooottttiiiicccceeee(((())))
           void sendFileNotice(char* op, char* file,
                               int argc, VkMsgArg* argv);


          Same as the _s_e_n_d_N_o_t_i_c_e() method, except sets the filename attribute
          to the second argument.

           void sendFileNotice(char* op, char* file);


          Same as the _s_e_n_d_N_o_t_i_c_e() _m_e_t_h_o_d, _e_x_c_e_p_t _s_e_t_s _t_h_e _f_i_l_e_n_a_m_e _a_t_t_r_i_b_u_t_e
          _t_o _t_h_e _s_e_c_o_n_d _a_r_g_u_m_e_n_t.

   sssseeeennnnddddSSSSttttrrrriiiinnnnggggFFFFiiiilllleeeeNNNNoooottttiiiicccceeee(((())))
           void sendStringFileNotice(char* op, char* file ...);


          Same as the _s_e_n_d_S_t_r_i_n_g_N_o_t_i_c_e() method, except sets the filename
          attribute to the second argument.

   sssseeeennnnddddIIIInnnnttttFFFFiiiilllleeeeNNNNoooottttiiiicccceeee(((())))
           void sendIntFileNotice(char* op, char* file ...);


          Same as the _s_e_n_d_I_n_t_N_o_t_i_c_e() method, except sets the filename
          attribute to the second argument.

   sssseeeennnnddddRRRReeeeqqqquuuueeeesssstttt(((())))
           VkMsgMessage sendRequest(char* op, int argc,
                                    VkMsgArg* argv);


          Send a request.  The first argument is the operator string, the
          second argument is the number of message arguments, and the third
          argument is the array of message arguments.






                                                                        PPPPaaaaggggeeee 6666






VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))                                                VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))



           VkMsgMessage sendRequest(char* op);


          Send a request.  The first argument is the operator string, and the
          composed message arguments list is used (see the _c_o_m_p_o_s_e_B_e_g_i_n() and
          _c_o_m_p_o_s_e_A_d_d() methods).

   sssseeeennnnddddSSSSyyyynnnnccccRRRReeeeqqqquuuueeeesssstttt(((())))
           VkMsgMessage sendSyncRequest(char* op, int argc,
                                        VkMsgArg* argv,
                              int timeout = DEFAULT_SYNC_TIMEOUT);


          Like the _s_e_n_d_R_e_q_u_e_s_t() method, but simulates a synchronous request
          where we wait for the reply message.  The reply message is returned,
          NULL if no reply was received within the timeout period.  The last
          argument specifies the timeout period in seconds, and defaults to
          60.  The resource value for "defaultSyncTimeout" will override this
          default.  Using a timeout of zero will disable the timeout
          completely.  Use VkMsgDestroy to destroy the reply when done.

           VkMsgMessage sendSyncRequest(char* op,
                       int timeout = DEFAULT_SYNC_TIMEOUT);


          Like the _s_e_n_d_S_y_n_c_R_e_q_u_e_s_t() method, but uses the composed message
          arguments list.

   sssseeeennnnddddFFFFiiiilllleeeeRRRReeeeqqqquuuueeeesssstttt(((())))
           VkMsgMessage sendFileRequest(char* op, char* file,
                                        int argc, VkMsgArg* argv);


          Like the _s_e_n_d_R_e_q_u_e_s_t() method, but sets the filename attribute to
          the second argument.

           VkMsgMessage sendFileRequest(char* op, char* file);


          Like the _s_e_n_d_R_e_q_u_e_s_t() method, but sets the filename attribute to
          the second argument.

   sssseeeennnnddddSSSSyyyynnnnccccFFFFiiiilllleeeeRRRReeeeqqqquuuueeeesssstttt(((())))
           VkMsgMessage sendSyncFileRequest(char* op, char* file,
                                           int argv, VkMsgArg* argv,
                               int timeout = DEFAULT_SYNC_TIMEOUT);


          Like the _s_e_n_d_S_y_n_c_R_e_q_u_e_s_t() method, but sets the filename attribute
          to the second argument.





                                                                        PPPPaaaaggggeeee 7777






VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))                                                VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))



           VkMsgMessage sendSyncFileRequest(char* op, char* file,
                           int timeout = DEFAULT_SYNC_TIMEOUT);


          Like the _s_e_n_d_S_y_n_c_R_e_q_u_e_s_t() method, but sets the filename attribute
          to the second argument.

   ccccoooommmmppppoooosssseeeeBBBBeeeeggggiiiinnnn(((())))
           void composeBegin(void);


          Initialize and clear the composed message arguments list.

   ccccoooommmmppppoooosssseeeeAAAAdddddddd(((())))
           void composeAdd(VkMsgArg* arg);


          Add an argument to the composed message arguments list.  The
          _V_k_M_s_g_A_r_g structure contains the type, value, and mode of the
          argument.

           void composeAdd(char* val,
                           VkMsgMode mode = VK_MSG_IN);


          Add a string argument to the composed message arguments list.  The
          second argument indicates the mode, and defaults to _V_K__M_S_G__I_N.

           void composeAdd(int ival,
                           VkMsgMode mode = VK_MSG_IN);


          Add an integer argument to the composed message arguments list.  The
          second argument indicates the mode, and defaults to _V_K__M_S_G__I_N.

           void composeAdd(unsigned char* bval,
                           int len,
                           VkMsgMode mode = VK_MSG_IN);


          Add a binary string argument to the composed message arguments list.
          The second argument indicates the mode, and defaults to _V_K__M_S_G__I_N.

   ccccoooommmmppppoooosssseeeeLLLLiiiisssstttt(((())))
           VkMsgArg* composeList(void);


          Returns the composed message arguments list.

   ccccoooommmmppppoooosssseeeeNNNNuuuummmm(((())))





                                                                        PPPPaaaaggggeeee 8888






VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))                                                VVVVkkkkMMMMssssggggCCCClllliiiieeeennnntttt((((3333xxxx))))



           int composeNum(void);


          Returns the size of the composed message arguments list.

   rrrreeeeggggiiiisssstttteeeerrrrPPPPaaaatttttttteeeerrrrnnnn(((())))
           VkMsgStatus registerPattern(VkMsgPattern pat);


          Register a pattern created by the createPattern method and express
          interests in those messages.  Once a pattern is registered, messages
          will be received which match the pattern.

   uuuunnnnrrrreeeeggggiiiisssstttteeeerrrrPPPPaaaatttttttteeeerrrrnnnn(((())))
           VkMsgStatus unregisterPattern(VkMsgPattern pat);


          Unregister a previously-registered pattern from the registerPattern
          method.  Messages will no longer be received for that pattern.

   ddddeeeessssttttrrrrooooyyyyPPPPaaaatttttttteeeerrrrnnnn(((())))
           VkMsgStatus destroyPattern(VkMsgPattern pat);


          Destroy patterns created by the registerPattern or createPattern
          methods.  Destroying a pattern automatically unregisters it.

CCCCLLLLAAAASSSSSSSSEEEESSSS UUUUSSSSEEEEDDDD BBBBYYYY TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS
     VkMsgFacility, VkMsgService

KKKKNNNNOOOOWWWWNNNN CCCCLLLLAAAASSSSSSSSEEEESSSS TTTTHHHHAAAATTTT UUUUSSSSEEEE TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS
     VkMsgApp, VkMsgClient, VkMsgComponent, VkMsgService, VkMsgWindow

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     VkMsgApp, VkMsgClient, VkMsgComponent, VkMsgFacility, VkMsgService,
     VkMsgWindow
     _V_i_e_w_K_i_t _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e
     _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m, DEC Press, Bob Sheifler and Jim Gettys
     _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m _T_o_o_l_k_i_t, DEC Press, Paul Asente and Ralph Swick
     _T_h_e _O_S_F/_M_o_t_i_f _P_r_o_g_r_a_m_m_e_r_s _R_e_f_e_r_e_n_c_e, Prentice Hall, OSF















                                                                        PPPPaaaaggggeeee 9999